Callblast Web Interface
========================

Overview
--------

The Callblast web interface allows internal users to send voice broadcast jobs via a simple browser form.

The user must select the **correct company or ISP name** from a dropdown. This selection is critical:
it allows the backend to automatically populate the correct ISP ID, account code, caller ID, and api key
used for callblast routing and authorization. These values are **not visible or editable** in the form.

Form Fields
-----------

+------------+--------+------------------------------------------------------------------+
| Field      | Type   | Description                                                      |
+============+========+==================================================================+
| ISP Name   | select | Company or ISP from the dropdown. Used internally to auto-fill   |
|            |        | ISP ID, account code, caller ID, and api key.                    |
+------------+--------+------------------------------------------------------------------+
| message    | string | The message to be converted into speech                          |
|            |        | (must be 5–1000 characters)                                      |
+------------+--------+------------------------------------------------------------------+
| numbers    | text   | Comma-, line-, or newline-separated list of phone numbers        |
|            |        | (each 10–15 digits; non-digit characters will be stripped)       |
+------------+--------+------------------------------------------------------------------+

Example Submission (form-urlencoded)
------------------------------------

.. code-block:: none

    message=System+maintenance+will+start+at+5+PM.
    numbers=09181234567%2C09991234567

Validation Rules
----------------

- You must select a valid company/ISP from the dropdown
- `message` must not be blank
- Must be at least 5 characters and no more than 1000
- `numbers` must be 10–15 digit-only values
- The request does not proceed if even a single phone number is invalid — all numbers must pass validation.

Success Response
----------------

.. code-block:: json

    {
        "status": "queued",
        "targets": 2
    }

Error Responses
---------------

.. code-block:: json

    {
        "error": "Message cannot be empty."
    }

.. code-block:: json

    {
        "error": "Message is too long (maximum is 1000 characters)."
    }

.. code-block:: json

    {
        "error": "The following phone numbers are invalid: 123abc, 999"
    }

.. code-block:: json

    {
        "error": "No valid phone numbers provided."
    }

Notes
-----

- The company, caller ID, account code, and authentication key are selected automatically based on the ISP name chosen by the user
- Messages are converted to speech using a text-to-speech engine
- The request will be rejected if any phone number is invalid — only fully valid lists are accepted for processing.